home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / EnterFile.3 < prev    next >
Encoding:
Text File  |  1994-12-17  |  3.2 KB  |  86 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) EnterFile.3 1.5 94/12/17 16:17:19
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_EnterFile tclc 7.0
  12. .BS
  13. .SH NAME
  14. Tcl_EnterFile, Tcl_GetOpenFile, Tcl_FilePermissions \- manipulate the table of open files
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. \fBTcl_EnterFile\fR(\fIinterp, file, permissions\fR)
  20. .sp
  21. int
  22. \fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
  23. .sp
  24. int
  25. \fBTcl_FilePermissions(\fIfile\fR)
  26. .SH ARGUMENTS
  27. .AS Tcl_Interp checkUsage
  28. .AP Tcl_Interp *interp in
  29. Tcl interpreter from which file is to be accessed.
  30. .AP FILE *file in
  31. Handle for file that is to become accessible in \fIinterp\fR.
  32. .AP int permissions in
  33. OR-ed combination of TCL_FILE_READABLE and TCL_FILE_WRITABLE; 
  34. indicates whether \fIfile\fR was opened for reading or writing or both.
  35. .AP char *string in
  36. String identifying file, such as \fBstdin\fR or \fBfile4\fR.
  37. .AP int write in
  38. Non-zero means the file will be used for writing, zero means it will
  39. be used for reading.
  40. .AP int checkUsage in
  41. If non-zero, then an error will be generated if the file wasn't opened
  42. for the access indicated by \fIwrite\fR.
  43. .AP FILE **filePtr out
  44. Points to word in which to store pointer to FILE structure for
  45. the file given by \fIstring\fR.
  46. .BE
  47.  
  48. .SH DESCRIPTION
  49. .PP
  50. These procedures provide access to Tcl's file naming mechanism.
  51. \fBTcl_EnterFile\fR enters an open file into Tcl's file table so
  52. that it can be accessed using Tcl commands like \fBgets\fR,
  53. \fBputs\fR, \fBseek\fR, and \fBclose\fR.
  54. It returns in \fIinterp->result\fR an identifier such as \fBfile4\fR
  55. that can be used to refer to the file in subsequent Tcl commands.
  56. \fBTcl_EnterFile\fR is typically used to implement new Tcl commands
  57. that open sockets, pipes, or other kinds of files not already supported
  58. by the built-in commands.
  59. .PP
  60. \fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
  61. returned by the \fBopen\fR command or \fBTcl_EnterFile\fR and
  62. returns at \fI*filePtr\fR a pointer to the FILE structure for
  63. the file.
  64. The \fIwrite\fR argument indicates whether the FILE pointer will
  65. be used for reading or writing.
  66. In some cases, such as a file that connects to a pipeline of
  67. subprocesses, different FILE pointers will be returned for reading
  68. and writing.
  69. \fBTcl_GetOpenFile\fR normally returns TCL_OK.
  70. If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
  71. make any sense or \fIcheckUsage\fR was set and the file wasn't opened
  72. for the access specified by \fIwrite\fR) then TCL_ERROR is returned
  73. and \fIinterp->result\fR will contain an error message.
  74. If \fIcheckUsage\fR is zero and the file wasn't opened for the
  75. access specified by \fIwrite\fR, then the FILE pointer returned
  76. at \fI*filePtr\fR may not correspond to \fIwrite\fR.
  77. .PP
  78. \fBTcl_FilePermissions\fR returns an OR-ed combination of the
  79. mask bits TCL_FILE_READABLE and TCL_FILE_WRITABLE; these indicate
  80. whether the given file was opened for reading or writing or both.
  81. If \fIfile\fR does not refer to a file in Tcl's file table then
  82. \-1 is returned.
  83.  
  84. .SH KEYWORDS
  85. file table, permissions, pipeline, read, write
  86.